home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1995…tember: Reference Library / Dev.CD Sep 95 RL / Dev.CD Sep 95 RL.toast / mac / Technical Documentation / develop / develop Issue 22 code / PCI Driver Sample / NCR_DriverProject / Src / ManageNVRAMProperty.c < prev    next >
Encoding:
C/C++ Source or Header  |  1995-03-19  |  9.4 KB  |  296 lines  |  [TEXT/MPCC]
  1. /*                                    ManageNVRAMProperty.c                            */
  2. /*
  3.  * ManageNVRAMProperty.c
  4.  * Copyright © 1994-95 Apple Computer Inc. All rights reserved.
  5.  *
  6.  */
  7. /*    .___________________________________________________________________________________.
  8.       | These routines, after modification, will be useful for other drivers. There are    |
  9.       | several general-purpuse routines that simplify access to the Name Registry. There    |
  10.     | are also some routines that are specific to the sample driver that will be useful    |
  11.     | for other drivers after modification.                                                |
  12.     .___________________________________________________________________________________.
  13. */
  14.  
  15. #include "NCRDriverPrivate.h"
  16.  
  17. #define CopyOSTypeToCString(osTypePtr, resultString) do {        \
  18.         BlockCopy(osTypePtr, resultString, sizeof (OSType));    \
  19.         resultString[sizeof (OSType)] = 0;                        \
  20.     } while (0)
  21.  
  22.  
  23. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  24.  * RetrieveDriverNVRAMParameter retrieves the single property stored in non-volatile
  25.  * memory (NVRAM). By convention, this property is named using our registered
  26.  * creator code. Because the PCI system stores properties indexed by physical slot
  27.  * number, we may retrieve an incorrect property if the user moves cards around.
  28.  * To protect against this, we check the property name.
  29.  *
  30.  * This function must be called from an initialization context.
  31.  *
  32.  * Return status:
  33.  *    noErr            Success: the NVRAM property was retrieved.
  34.  *    nrNotFoundErr    Failure: there was no NVRAM property.
  35.  *    paramErr        Failure: there was an NVRAM property, but not ours.
  36.  *                            (We deleted it.)
  37.  *    other            Failure: unexpected Name Registry error.
  38.  */
  39. OSErr
  40. RetrieveDriverNVRAMProperty(
  41.         RegEntryIDPtr            regEntryIDPtr,        /* Driver's Name Registery ID    */
  42.         OSType                    driverCreatorID,    /* Registered creator code        */
  43.         UInt8                    driverNVRAMRecord[8]
  44.     )
  45. {
  46.         OSErr                    status;
  47.         RegPropertyIter            cookie;
  48.         RegPropertyNameBuf        propertyName;
  49.         RegPropertyValueSize    regPropertyValueSize;
  50.         RegPropertyModifiers    propertyModifiers;
  51.         Boolean                    done;
  52.         char                    creatorNameString[sizeof (OSType) + 1];
  53.  
  54.         /*
  55.          * Search our properties for one with the NVRAM modifier set.
  56.          */
  57.         status = RegistryPropertyIterateCreate(regEntryIDPtr, &cookie);
  58.         if (status == noErr) {
  59.             while (status == noErr) {
  60.                 /*
  61.                  * Get the next property and check its modifier. Break if this is the
  62.                  * NVRAM property (there can be only one for our entry ID).
  63.                  */
  64.                 status = RegistryPropertyIterate(&cookie, propertyName, &done);
  65.                 if (status == noErr && done == FALSE) {
  66.                     status = RegistryPropertyGetMod(
  67.                                 regEntryIDPtr,
  68.                                 propertyName,
  69.                                 &propertyModifiers
  70.                             );
  71.                     CheckStatus(status, "\pRegistryPropertyGetMod NVRAM failed");
  72.                     if (status == noErr
  73.                      && (propertyModifiers & kRegPropertyValueIsSavedToNVRAM) != 0)
  74.                         break;
  75.                 }
  76.                 /*
  77.                  * There was no NVRAM property. Return nrNotFoundErr by convention.
  78.                  */
  79.                 if (status == noErr && done)
  80.                     status = nrNotFoundErr;
  81.             }
  82.             RegistryPropertyIterateDispose(&cookie);
  83.             /*
  84.              * If status == noErr, we have found an NVRAM property. Now,
  85.              *    1. If it is our creator code, we have found the property, so
  86.              *        we retrieve the values and store them in the driver's globals.
  87.              *    2. If it was found with a different creator code, the user has
  88.              *        moved our card to a slot that previously had a different card
  89.              *        installed, so delete this property and return (noErr) to use
  90.              *        the factory defaults.
  91.              *    3. If it was not found, the property was not set, so we exit
  92.              *        (noErr) -- the caller will have pre-set the values to
  93.              *        "factory defaults."
  94.              */
  95.             if (status == noErr) {
  96.                 /*
  97.                  * Cases 1 or 2, check the property.
  98.                  */
  99.                 CopyOSTypeToCString(&driverCreatorID, creatorNameString);
  100.                 if (CStrCmp(creatorNameString, propertyName) == 0) {    /* Match     */
  101.                     status = RegistryPropertyGetSize(
  102.                                 regEntryIDPtr,
  103.                                 propertyName,
  104.                                 ®PropertyValueSize
  105.                             );
  106.                     CheckStatus(status, "\pRegistryPropertyGetSize NVRAM failed");
  107.                     if (status == noErr
  108.                      && regPropertyValueSize == sizeof driverNVRAMRecord) {
  109.                         status = RegistryPropertyGet(
  110.                                     regEntryIDPtr,
  111.                                     propertyName,
  112.                                     driverNVRAMRecord,
  113.                                     ®PropertyValueSize
  114.                                 );
  115.                         CheckStatus(status, "\pRegistryPropertyGet NVRAM failed");
  116.                     }
  117.                 }
  118.                 else {
  119.                     /*
  120.                      * This is an NVRAM property, but it isn't ours. Delete the
  121.                      * property and return an error status so the caller uses
  122.                      * "factory settings"
  123.                      */
  124.                     status = RegistryPropertyDelete(
  125.                                 regEntryIDPtr,
  126.                                 propertyName
  127.                             );
  128.                     CheckStatus(status, "\pRegistryPropertyDelete bad NVRAM entry");
  129.                     /*
  130.                      * Since we're returning an error anyway, we ignore the
  131.                      * status code.
  132.                      */
  133.                     status = paramErr;
  134.                 }
  135.             }
  136.         }
  137.         return (status);
  138. }
  139.  
  140. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  141.  * Get the NVRAM property. Return an error if it does not exist, is the wrong size, or
  142.  * is not marked "store in NVRAM." This may be called from a non-initialization context.
  143.  * Errors:
  144.  *    nrNotFoundErr        Not found in the registry
  145.  *    nrDataTruncatedErr    Wrong size
  146.  *    paramErr            Not marked "store in NVRAM"
  147.  */
  148. OSErr
  149. GetDriverNVRAMProperty(
  150.         RegEntryIDPtr            regEntryIDPtr,            /* Driver's Name Registery ID    */
  151.         OSType                    driverCreatorID,        /* Registered creator code        */
  152.         UInt8                    driverNVRAMRecord[8]    /* Mandated size                */
  153.     )
  154. {
  155.         OSErr                    status;
  156.         char                    creatorNameString[sizeof (OSType) + 1];
  157.         RegPropertyValueSize    size;
  158.         RegPropertyModifiers    modifiers;
  159.  
  160.         CopyOSTypeToCString(&driverCreatorID, creatorNameString);
  161.         status = RegistryPropertyGetSize(
  162.             regEntryIDPtr,
  163.             creatorNameString,
  164.             &size
  165.         );
  166.         if (status == noErr && size != sizeof driverNVRAMRecord)
  167.             status = nrDataTruncatedErr;
  168.         if (status == noErr) {
  169.             status = RegistryPropertyGetMod(
  170.                         regEntryIDPtr,
  171.                         creatorNameString,
  172.                         &modifiers
  173.                     );
  174.         }
  175.         if (status == noErr
  176.          && (modifiers & kRegPropertyValueIsSavedToNVRAM) == 0)
  177.              status = paramErr;
  178.         if (status == noErr) {
  179.             status = RegistryPropertyGet(
  180.                         regEntryIDPtr,
  181.                         creatorNameString,
  182.                         driverNVRAMRecord,
  183.                         &size
  184.                     );
  185.         }
  186.         return (status);
  187. }
  188.  
  189. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  190.  * Update the NVRAM property. Return an error if it was not created. This may be called
  191.  * from PBStatus (or other non-initialization context).
  192.  */
  193. OSErr
  194. UpdateDriverNVRAMProperty(
  195.         RegEntryIDPtr            regEntryIDPtr,            /* Driver's Name Registery ID    */
  196.         OSType                    driverCreatorID,        /* Registered creator code        */
  197.         UInt8                    driverNVRAMRecord[8]    /* Mandated size                */
  198.     )
  199. {
  200.         OSErr                    status;
  201.         char                    creatorNameString[sizeof (OSType) + 1];
  202.  
  203.         Trace(UpdateDriverNVRAMProperty);
  204.         CopyOSTypeToCString(&driverCreatorID, creatorNameString);
  205.         /*
  206.          * Replace the current value of the property with its new value. In this
  207.          * example, we are replacing the entire value and, potentially, changing
  208.          * its size. In production software, you may need to read an existing
  209.          * property and modify its contents. This shouldn't be too hard to do.
  210.          */
  211.         status = RegistryPropertySet(        /* Update existing value                */
  212.                     regEntryIDPtr,
  213.                     creatorNameString,
  214.                     driverNVRAMRecord,
  215.                     sizeof driverNVRAMRecord
  216.                 );
  217.         CheckStatus(status, "\pStoreDriverNVRAMProperty");
  218.         return (status);
  219. }
  220.  
  221. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  222.  * Create the NVRAM property. This must be called from the driver initialization function.
  223.  */
  224. OSErr
  225. CreateDriverNVRAMProperty(
  226.         RegEntryIDPtr            regEntryIDPtr,            /* Driver's Name Registery ID    */
  227.         OSType                    driverCreatorID,        /* Registered creator code        */
  228.         UInt8                    driverNVRAMRecord[8]    /* Mandated size                */
  229.     )
  230. {
  231.         OSErr                    status;
  232.         char                    creatorNameString[sizeof (OSType) + 1];
  233.         RegPropertyValueSize    size;
  234.         RegPropertyModifiers    modifiers;
  235.  
  236.         Trace(CreateDriverNVRAMProperty);
  237.         CopyOSTypeToCString(&driverCreatorID, creatorNameString);
  238.         /*
  239.          * Does the property currently exist (with the correct size)?
  240.          */
  241.         status = RegistryPropertyGetSize(        /* returns noErr if the property exists    */
  242.                     regEntryIDPtr,
  243.                     creatorNameString,
  244.                     &size
  245.                 );
  246.         if (status == noErr) {
  247.             /*
  248.              * Replace the current value of the property with its new value. In this
  249.              * example, we are replacing the entire value and, potentially, changing
  250.              * its size. In production software, you may need to read an existing
  251.              * property and modify its contents. This shouldn't be too hard to do.
  252.              */
  253.             status = RegistryPropertySet(        /* Update existing value                */
  254.                         regEntryIDPtr,
  255.                         creatorNameString,
  256.                         driverNVRAMRecord,
  257.                         sizeof driverNVRAMRecord
  258.                     );
  259.         }
  260.         else {
  261.             status = RegistryPropertyCreate(    /* Make a new property                    */
  262.                         regEntryIDPtr,
  263.                         creatorNameString,
  264.                         driverNVRAMRecord,
  265.                         sizeof driverNVRAMRecord
  266.                     );
  267.         }
  268.         /*
  269.          * If status equals noErr, the property has been stored; set its "save to
  270.          * non-volatile ram" bit.
  271.          */
  272.         if (status == noErr) {
  273.             status = RegistryPropertyGetMod(
  274.                         regEntryIDPtr,
  275.                         creatorNameString,
  276.                         &modifiers
  277.                     );
  278.         }
  279.         if (status == noErr) {
  280.             /*
  281.              * Set the NVRAM bit and update the modifiers.
  282.              */
  283.             modifiers |= kRegPropertyValueIsSavedToNVRAM;
  284.             status = RegistryPropertySetMod(
  285.                         regEntryIDPtr,
  286.                         creatorNameString,
  287.                         modifiers
  288.                     );
  289.         }            
  290.         CheckStatus(status, "\pCreateDriverNVRAMProperty");
  291.         return (status);
  292. }
  293.  
  294.  
  295.  
  296.